MacWorld 1997 September

home *** CD-ROM | disk | FTP | other *** search

/ MacWorld 1997 September / Macworld (1997-09).dmg / Serious Software / Cherwell Scientific Demos / pro Fit / pro Fit 5.0 demo (fpu).sea / pro Fit 5.0 demo (fpu) / External Modules / External modules sources / C / proFit_interface.h < prev next >

Wrap

Text File | 1996-06-01 | 68KB | 1,780 lines

/***************************************************************************************/ /* proFit_interface.h */ /* */ /* */ /* Version history */ /* 15.12.95: orig 5.0A9 release */ /* 20.02.96: added SetWindowInfo, SetBoxTitle, InputBox for strings */ /* 10.03.96: added GetFunctionParamName, CancelEvent */ /* 15.03.96: added NumberToStr255, Str255ToNumber */ /* 17.03.96: added GetAndSetStatus */ /* 24.03.96: added SetTextFileFormat, changed SaveDataAsText */ /***************************************************************************************/ #ifndef __PROFIT_INTERFACE__ #define __PROFIT_INTERFACE__ /**************************************************************************************** Welcome to the pro Fit external modules! --------------------------------------- External modules are pieces of code that you produce with your favorite compiler and that you can build into pro Fit as functions or "user" programs. If it is the first time you do something with external modules and you want to see what is needed to implement them, just take a look at the example files. For example you might want to study file ErrorFunc.c and look at the functions that are defined there. Most function names are the same ones used for defining functions and programs within pro Fit. To define your own external module, simply fill in these functions with your code. Have a look at the pro Fit user manual for details on the parameter lists of these functions. In order to build an external function or program, you must compile and link the following files: proFit_interface.c ("glue" code standing between pro Fit and your functions) XXXXXX.c (your functions, where XXXXXX is a name you define) Of course you can add other files if you need them (such as math.c from the ANSI libraries). Also, depending on the compiler you use, you may have to add additional modules containing call glues for system traps (for example, in ThinkC you must add "MacTraps" to your project). You must use the following header files: proFit_interface.h (This file) contains the definitions of the functions you must define and all the routines provided by pro Fit. These routines implement the functionality of all predefined routines that are available when defining a function or a program within pro Fit. These routines are implemented in proFit_interface.c proFit_paramBlk.h Contains the definition of ExtModulesParamBlock, a struct used to interact with pro Fit and call various pro Fit routines. Advanced programmers can use this definition if they feel they need to. Using the information given in this file may, however, cause compatibility problems with future versions of pro Fit. Compiling instructions for Power Macintosh (PowerPC): ----------------------------------------------------- Compile your files as a "shared libary" or, more accurately, as an "application extension". The code should reside in the data fork (not a resource) and it should export the function main() as it is defined in proFit_interface.c. The type of the file you create must be 'ftCD', its creator must be 'NLft'. Compiling instructions for 68XXX: --------------------------------- Compile your files and link them in a single resource of type 'NLft' (the ID number can be any number >128 you like). Make sure that your code consists of a single segment. Refer to your compiler's manual if you don't know how to compile code for a resource. Put your resource into a file having the type 'ftCD' and the creator 'NLft'. Before compiling, make sure that you choose the compiler options that are compatible with the version of pro Fit you use: If you use the FPU version of pro Fit, make sure that your double variables are 12 bytes long. Under ThinkC, check the options "Generate 68881/882 instructions" and "Native floating point format" in your compiler options. If you use the non-FPU version of pro Fit, make sure that your double variables are 10 bytes long. Under ThinkC, uncheck the option "Generate 68881/882 instructions" and check "Native floating point format" in your compiler options. The external module is a compiled code resource that provides a function called 'main'. You must make sure that main() is at the beginning of your code. Under Symantec's compilers, this is done automatically. Under MPW, you must make sure that main() is the first routine that is compiled and linked. ****************************************************************************************/ /**************************************************************************************** The following are the type definitions that serve as an interface between the external module and pro Fit. These declarations describe exactly how pro Fit expects the external module to arrange the information it provides, and how the information provided by pro Fit is arranged. Don't even think of changing something in this file. The informations it contains are vital to the external module in their present, original form. They are deadly if you modify them. ANY change in a type definition (e.g. changing the ranges of an array or the order of the fields in a record) is guaranteed to cause very ugly consequences. For a detailed description of these declarations andtheir use, see the pro Fit user manual. ****************************************************************************************/ /***************** general definitions used by external modules *****************/ #ifndef __TYPES__ #include <types.h> #endif enum {isFunction=1, isProgram, isMacro}; /* used in Setup to identify the external module */ #define drawingType 'ftGF' /* window types, used by DoNewWindow, etc.*/ #define dataType 'ftLS' #define textType 'ftFC' #define defaultType '****' enum { gaussDistr = 1, /* error distributions, used for setting the parameters of the SetFitDefaults routine */ doubleExpDistr, lorentzDistr, andrewDistr, tukeyDistrnoErrors }; enum { defaultFormat, /* Drawing window file formats */ pictFormat, epsFormat, floatColumn=0, /* data column types */ doubleColumn=1, textColumn = 128 }; #define noErrors 0 /* error bar types, used for setting the "errors" parameter in the "errors" parameter in the OpenDataSet routine*/ #define eBarY 1 #define eBarX 2 #define asymmEBarY 4 #define asymmEBarX 8 #define xAxis 0 /* used for the routines accessing the current x or y axis, such as "SetRange" */ #define yAxis 1 /* used to distinguish between Y and X axes. */ #define equalToMain 1 /* defines used for setting the "flags" field in calls to the SetAxisAttributes routine */ #define drawAxisLine 2 #define drawTicks 4 #define drawMajorTickLabels 8 #define drawMinorTickLabels 0x10 #define plusSideTicks 0x20 #define minusSideTicks 0x40 #define plusSideLabels 0x80 #define labelsOutsideFrame 0x0100 #define drawFrame 2 /* defines used for setting the "flags" field in calls to the SetGraphAttributes routine */ #define drawMajorGridX 4 #define drawMinorGridX 8 #define drawMajorGridY 0x10 #define drawMinorGridY 0x20 #define plotBehindAxes 0x40 #define gridInFront 0x80 #define gridInMiddle 0x0100 #define maxNrParams 64 /* the maximum number of parameters of a function */ #define maxParamNameLength 31 /* the maximum length of a parameter name */ #define maxNrInputValues 6 /* the maximum number of input values in the input dialog box */ #if defined(powerc) || defined (__powerc) #pragma options align=mac68k #endif typedef struct /* definition used by the function "InputBox"*/ { double* x; /* pointer to value or string (if s starts with $S */ unsigned char* s; } InputRec[maxNrInputValues]; #if defined(powerc) || defined (__powerc) #pragma options align=reset #endif /************* type definitions for "GetDefaultData" **************/ typedef struct /* this data structure can be used when calling GetDefaultData. */ { double xMin,xMax,xPosMin,xNegMax; /* set if the "x" array was calculated */ double yMin,yMax,yPosMin,yNegMax; /* set if the "y" array was calculated */ Boolean ordered; /* true if the x-array is ordered such that x[i+1]>=x[i], for all i. */ Boolean zeroYErrors; /* true if at least one y-error is 0 */ Boolean invalidYErrors; /* true if at least one y-error is invalid or 0 */ Boolean zeroXErrors; /* true if at least one x-error is 0 */ Boolean invalidXErrors; /* true if at least one x-error is invalid or 0 */ } DataInfo; typedef double DoubleArray[1]; /* variable size array of native double numbers */ typedef long LongArray[1]; /* variable size array of long numbers */ typedef DoubleArray** DoubleArrayHandle; /* Handle to an array of double */ typedef LongArray** LongArrayHandle; /* Handle to an array of long */ /************* type definitions for "GetColHandle/SetColHandle" ***************/ #if defined(powerc) || defined (__powerc) #pragma options align=mac68k #endif typedef struct /* the data structure of a column of strings. Warning: this data structure may change in future releases of pro Fit */ { long size; /* the size of valid data in this handle */ long nrRows; /* the number of rows in this handle */ long firstOffset; /* reserved */ short firstRow; /* reserved */ Str255 data; /* here follow the strings, packed, one after another */ } StringData; #if defined(powerc) || defined (__powerc) #pragma options align=reset #endif #if defined(powerc) || defined (__powerc) typedef double double_8; /* a 8 byte floating point number */ #else typedef short double double_8; /* a 8 byte floating point number */ #endif typedef float FloatColumnArray[1]; /* a variable size array of 4 byte doubles */ typedef double_8 DoubleColumnArray[1]; /* a variable size array of 8 byte doubles */ typedef FloatColumnArray** FloatColumnHandle; /* column handle for columns of type floatColumn */ typedef DoubleColumnArray** DoubleColumnHandle; /* column handle for columns of type doubleColumn */ typedef StringData** TextColumnHandle; /* column handle for columns of type textColumn */ typedef enum {update, good, bad} CheckPAnswer; /*the possible return values of the 'check' function, only used when the external module is a function */ typedef unsigned char ParamName[maxParamNameLength+1]; /* the names of the prameters */ enum {active, inactive, constant}; /* the fitting state of a parameter, used to set variables of type ParamMode */ typedef char ParamMode; /* the fitting mode of a parameter (active, inactive, constant) */ typedef double ParamArray[maxNrParams]; /* an array to hold the parameters */ typedef ParamMode ParamModeArray[maxNrParams]; /* the fitting modes of the parameters, {active, inactive, constant} */ typedef ParamName ParamNameArray[maxNrParams]; /* the names of the parameters */ #if defined(powerc) || defined (__powerc) #pragma options align=mac68k #endif typedef struct { ParamArray* value; /* the default value of the parameters as they appear in params window */ ParamArray* lowest; /* the lowest allowed value (for fitting) */ ParamArray* highest; /* the highest allowed value (for fitting) */ ParamModeArray* mode; /* the fitting mode of the parameters */ ParamNameArray* name; /* their names */ } DefaultParamInfo; typedef double GlobalArrayType[100]; typedef struct { long globalScratch1; /* freee for use in external modules */ long globalScratch2; /* freee for use in external modules */ long globalDataSize; /* the number of entries in the following array */ GlobalArrayType** globalData; /* array of doubles to be accessed by external and interal programs */ }GlobalScratch; #if defined(powerc) || defined (__powerc) #pragma options align=reset #endif #include "proFit_paramBlk.h" /************************************************************************************************/ /******************* functions that must be supplied by the external module ********************* the following are all the functions that the external module must, or can, supply. They are used in the procedure main, defined in profit_interface.c. All you need to know to program an external module for pro Fit are these prototypes. Just fill-in your code in the template files provided (FunctionTemplate.c and ProgramTemplate.c) ************************************************************************************************/ /********* ROUTINES USED BY ALL EXTERNAL MODULES (both functions and programs) ***************/ void SetUp ( short* const moduleKind, /* set moduleKind to isFunction or isProgram */ Str255 name, /* the name of the program or function (pascal string) */ long* const requiredGlobals, /* the number of bytes to be allocated in ExtModulesParamBlock.globals */ /* set requiredGlobals to 0 if you don't use this feature */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* SetUp is called once when the external module is linked to proFit */ void CleanUp (ExtModulesParamBlock* pb); /* called when the function or program is removed from pro Fit's menus */ /* in most cases, this function can be empty */ /************ ROUTINES USED WHEN THE EXTERNAL MODULE IS A FUNCTION ******************/ void InitializeFunc ( Boolean* const hasDerivatives, /* set this to true if you do calculate some derivatives (dyda[]) in the */ /* "Derivatives" function you define. Any derivatives you don't calculate will be calculated numerically by pro Fit */ Str255 descr1stLine, /* first line of the text in the parameter window */ Str255 descr2ndLine, /* second line of the text in the parameter window */ short* const numberOfParams, /* the number of parameters of the function */ DefaultParamInfo* const a0, /* the default names, values etc. of the parameters */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* InitializeFunc is called once (after SetUp has been called) when the external module is linked to proFit */ /* Used to set all the information needed to describe a function */ short Check(short paramNo, /* the parameter that was changed */ DefaultParamInfo* const a0, /* the default names, values etc of the paramters */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* Can be left emtpy (returning good) if not needed. */ /* called when the user has changed a value in the parameters window. This routine */ /* can then check if this parameters is fine. It can also change some of the */ /* other entries in a0. The returned values can be: */ /* good: return this value if you agree with the new parameter value */ /* update: return this value if you want the parameters window */ /* to be updated because you changed some of the values in a0 */ /* bad: return this value if you want the new parameter value to be refused */ void First ( ParamArray a, /* the new parameters */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* Can be left emtpy if not needed. */ /* Called whenever the parameters are changed. Can be used to accelerate */ /* some calculations. See manual for more info */ void Func ( double x, /* the x-value */ ParamArray a, /* the parameters */ double* const y, /* the y-value to be returned */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* called to calculate the y-value of the function for a given x and a given */ /* set of parameters */ void Derivatives(double x, /* the x-value */ ParamArray a, /* the parameters */ ParamArray dyda, /* the derivatives to be returned */ ExtModulesParamBlock* pb); /* the complete parameter block passed by pro Fit to the */ /* routines defined in this file. In most cases it can be ignored */ /* called to calculate the partial derivatives of the function with respect to */ /* its parameters. The elements of the array "dyda[i]" must be set to the derivatives of */ /* the function with respect to parameter number "i". If any dyda[i] is not set by */ /* this function, then the derivatives will be calculated numerically by pro Fit. */ /* If you set hasDerivatives to false in FuncInitialize, then ALL derivatives will always */ /* be calcuated numerically by pro Fit, no matter what you do in the function "Derivatives" */ /* If a derivative is too complicated to be calculated analytically, then don't set the */ /* corresponding "dyda". pro Fit will notice this and calculate that derivative numerically. */ /* If you are able to calculate the dyda analytically, do so! By doing this you will make */ /* fitting much, much faster. */ void Last (ExtModulesParamBlock* pb); /* Can be left emtpy if not needed. */ /* Called when calculating is through. See manual for more info */ /************ ROUTINES USED WHEN THE EXTERNAL MODULE IS A PROGRAM ******************/ void InitializeProg (ExtModulesParamBlock* pb); /* Can be left emtpy if not needed. */ /* called when the resource is linked to proFit after SetUp was called */ /* can be used to inititialize global variables, etc. */ void Run(ExtModulesParamBlock* pb); /* pro Fit calls this function when the name of the program is chosen from the Misc Menu*/ /* utility function, you can use it if you need it... */ void SetPascalStr(Str255 s1, const Str255 s2, short limit); /* copies s2 to s1, makes sure that s1 is shorter than limit */ /* function used internally in proFit_Interface.c */ ExtModulesParamBlock* GetPb(void); /* Returns the parameter block as passed to main(). Only advanced */ /* programmers may need this function. */ /* WARNING: the definition of ExtModulesParamBlock may change in future versions */ /* of pro Fit. Using it from within your function may cause compatibility problems */ /* with those future versions. */ /*************************************************************************************/ /****************************************************************************************/ /****************************************************************************************/ /**************************************************************************************** Prototypes of all routines provided by pro Fit. For an explaination of the meaning of the various parameters and the return values see the pro Fit user manual. */ /********************************************************************************/ /********************************** input/output ********************************/ short InputBox(short numItems, InputRec* r); /* Shows a dialog box with nrArgs (between 1 and 6=maxNrInputValues) input values r contains a title and a numeric field for every argument The default way to display an input value is an numberic edit field with a title If the title 'ttt' starts with a '$' other interface elements are displayed: - '$Wttt' shows a popup menu to select a data window - '$Cttt' shows a popup menu to select a column - '$Pmmm$ttt' shows a user defined popup menu 'mmm' (each entry separated by a ';') - '$Xttt' shows a check box - '$Sttt' shows an edit field to input a string InputBox returns 0 if user pressed ok, 1 if user pressed stop */ void SetBoxTitle(const Str255 title); /* Sets the title of the dialog box in the next call to InputBox. By default, this box does not have a title. */ short AlertBox(const Str255 m); /* shows an alert box with a message m (pascal string) AlertBox returns 0 if user pressed ok, 1 if user pressed stop */ short AskBox(short* const answer, const Str255 message); /* shows an alert box with a Yes and a No button and displays "message" answer is 0 for No and 1 for Yes or Stop The return value is 0 if user pressed Yes or No, 1 if user pressed stop */ void Write(const Str255); /* writes a string (pascal string) to the results window */ void Writeln(const Str255); /* writes a string (pascal string) to the results window and goes to next line */ void WriteText(long length, unsigned char * theText); /* writes a text to the results window. the pointer theText points to the first */ /* character of the text. "length" must give the length of the text */ void WriteInt(long i); /* writes an integer value to the results window */ void WriteNumber(double d); /* writes a floating point value to the results window */ void NumberToStr255(double x, Str255 s, short format, short digits); /* converts the number x into a string */ /* format/digits: controls the conversion process. */ /* format = 0: normal conversion */ /* if digits>0: the number of digits after the '.', */ /* if digits<0: the total number of digits (approx.) */ /* format = 1: optimized conversion, removes unnecessary trailing zeros after */ /* the decimal point, leading spaces, unecessary '+'-signs, etc */ /* digits: the number of digits */ short Str255ToNumber(Str255 s, double* const x); /* converts string s to a number x. s can be a numeric string or an expression */ /* return values: */ /* 0: conversion successful */ /* 1: x is infinite */ /* 2: s is empty */ /* 3: x is an NAN (invalid number) */ /* 4: user aborted calculation */ /* 5: run time error */ /********************************************************************************/ /********** redirecting text to the results window or to text files ***********/ long CreateTextFile(const Str255 fileName); /* creates a text file with the given name and returns a reference number used to identify this file. Call the routine WriteToTextFile() to redirect the output from calls to write/writln/writenumber into this file. */ void CloseTextFile(long fileRefNumber); /* Closes the text file with the given reference number. The calls to write/writln/writenumber is redirected back to the results window. */ void WriteToTextFile(long fileRefNumber); /* redirects the output of the pro Fit "write/writeln/writenumber" routines to the given text file. call this routine with fileRefNumber==0 to direct the text writing routines back to the results window. */ /********************************************************************************/ /**************** window and document management routines ***********************/ long GetFrontWindow(void); /* Returns the identification number of the frontmost window */ void DoNewWindow(long windowType); /* creates a new window. windowType can take one of the following values: drawingType: create a drawing window dataType: create a data window textType create a text window */ void SetCurrentWindow(long windowID); /* makes the window with the given ID number the current window to be used for data, plotting, writing, etc, depending on its type. */ long GetCurrentWindow(long windowType); /* returns the ID number of the current window of the given type windowType can take one of the following values drawingType: return the current drawing window dataType: return the current data window textType return the current text window */ void DoCloseWindow(long windowID, Boolean saveIt); /* closes the window with the given ID number. saves the contents of the window if saveIt is true */ long FrontmostWindow(long windowType); /* returns the ID number of the front most window with the given type drawingType: return the frontmost drawing window dataType: return the frontmost data window textType return the frontmost text window */ void SaveWindow(long windowID); /* saves the contents of the given window in the file associated with it */ void SaveWindowAs(long windowID, const Str255 fileName); /* saves the contents of the given window in the file. fileName: the files name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". if fileName is an empty string, the window is saved in a file having the name of the window if fileName is "\p?", a dialog box is brought up to ask for user for a name */ long GetWindowID(const Str255 windowName); /* returns the ID number of the window with the given name. returns 0 if no such window is found. */ long GetWindowType(long windowID); /* returns the type of the window with the given ID number returns 0 if the given window is not a text, drawing or data window or if there is no window exists with the given ID number */ long NextWindow(long windowID); /* returns the ID number of the window immediately behind the given window returns 0 if the given window is the last one returns the front window if 0 is passed for the windowID. returns 0 and causes run-time error if the windowID it receives is invalid */ void OpenFile(const Str255 fileName); /* Opens the given file in a new window. fileName: the files name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". Set name to "\p?" for bringing up a dialog box prompting the user for the name. A run-time error occurs if the file cannot be opened. */ void OpenData(const Str255 fileName); /* Opens the given file as a data file. The file must either be a pro Fit data file or a text file with valid data. fileName: the files name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". Set name to "\p?" for bringing up a dialog box prompting the user for the name. A run-time error occurs if the file cannot be opened. */ void OpenText(const Str255 fileName); /* Opens the given file as a text file. The file must either be a pro Fit function file or a text file. fileName: the files name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". Set name to "\p?" for bringing up a dialog box prompting the user for the name. A run-time error occurs if the file cannot be opened. */ void SetTextFileFormat(const Str255 colDelimiter, const Str255 endOfLine, Boolean withColTitles, Boolean copyInfoText, long nrHeaderLines, long inputORoutput); /* colDelimiter: inserted between consecutive cells in the same row. Usually, you will specify a tab character by passing "\p\t" endOfLine: inserted between the last cell of a row and the first cell of a next row. Usually, you will specify the CR character by passing "\p\15" withColTitles: pass true if the column titles should be saved / loaded as the (first) row of the file. copyInfoText: pass true if the text in the info field of the data window should be saved / loaded at the beginning of the file nrHeaderLines: number of header lines contained in the text file when loading. If copyInfoText is true, these lines are copied to the info field, otherwise they are skipped. inputORoutput: pass 1 to define the format of an input file (loading), pass 0 to define the format of an output file (saving). */ void SaveDataAsText(long windowID, const Str255 fileName); /* saves the contents of the data window in a file. fileName: the file's name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". if fileName is an empty string, the window is saved in a file having the name of the window if fileName is "\p?", a dialog box is brought up to ask for user for a name The individual cells will be stored row by row. To set the format of the text file, use SetTextFileFormat */ void SaveDrawingAs(long windowID, const Str255 fileName,long format); /* saves the contents of the drawing window in a file. fileName: the file's name. If fileName does not contain a file path, the file is expected to reside in the same folder as pro Fit. Alternatively, you can specify a file path, such as "\pHD:MyFolder:My File". if fileName is an empty string, the window is saved in a file having the name of the window if fileName is "\p?", a dialog box is brought up to ask for user for a name format: 0 for saving the file in a standard pro Fit drawing file 1 for saving the file as picture (having a file type PICT) 2 for saving the fiel as eps-file (having a file type EPSF) */ void SetWindowTitle(long windowID, const Str255 name); /* sets the title of a given window. The title should not contain a ':' */ void GetWindowTitle(long windowID, Str255 name); /* returns the title of the window with the given windowID */ void SetWindowInfo(long windowID, long length, Ptr info); /* Sets the info of a window. (The "info" of a window can be viewed by using the Get Info... command from the File menu. For data windows, it is the text that appears when you drag down the info field.) windowID: the id of the window length: the length of the text in bytes info: a pointer to the start of the text Use SetWindow(windowID, 0, nil) for clearing the info field. */ void PlaceWindow(long windowID, Rect windowRect); /* resizes and positions the window according to windowRect */ void BringWindowToFront(long windowID); /* the window with the given ID number is brought in front of all others. */ void Compile(long windowID); /* Compiles the text found in the given window. Causes a run error if the given window is not a function window or if the text is not compiled successfully. */ /********************************************************************************/ /************************** drawing and plotting ********************************/ void OpenCurve(const Str255 curveName); /* Starts a new function curve definition in the current graph. After this call, all moveto/lineto calls will generate lines in the current graph. The function curve will use the current style/color, set by SetLineStyle/SetLineColor curveName is the name that will appear in the legend (pascal string). Call CloseCurve once you are finished. This function replaces the obsolete "NewCurve" function, used in earlier versions */ void CloseCurve(void); /* Matches the "OpenCurve" call. Stops collecting moveto/lineto calls as a definition of a function curve in the current graph. Call once you are finished defining a curve in the current graph. */ void OpenDataSet(short errors, Boolean connected, const Str255 datasetName); /* Starts a new data set definition in the current graph. After this call, all DrawDataPoint calls will generate data points in the current graph. AddDataPoint is also used for the same purposes, if you want to add error bars to the data point. The data set will use the current style/color, set by SetLineStyle/SetLineColor datasetName is the name that will appear in the legend. Call CloseDataSet once you are finished. errors: used to specify if the new data set will use error bars or not. pass 0 if you don't plan to use error bars, pass a sum of eBarY, eBarX, asymmEBarY, asymmEBarX to specify which kind of error bars you will use. connect: set to true if you want a line to coonnectthe data points. Example "eBarY+asymmEBarX" tells proFit that it has to allocate space for holding the value of the y error bar and the two values corresponding to the left and right part of an x error bar. When you then call AddDataPoint, the parameters yErr, xErr, and xErr1 will be interpreted by proFit. This function replaces the obsolete "NewDataSet" function, used in earlier versions */ void CloseDataSet(void); /* Matches the "OpenDataSet" call. Stops collecting AddDataPoint/DrawDataPoint calls as a definition of a data set in the current graph. */ void SetCurveFill(short whichAxis, short axisID); /* switches on the filling style for curves that will be created in the current graph using the OpenDataSet and OpenCurve functions. the parameters to this routine specify the axis towards which the filling is applied. use axisID==0 to swich off filling. Specify the filling color using the "SetFillColor" routine. */ void SetEBarStyle(double caplength, double capThick, double lineThick); /* sets the default error bar style used for producing error bars in the next data set created in the current graph using the OpenDataSet call */ void AddDataPoint(double x, double y, double xErr, double yErr, double xErr1, double yErr1); /* Adds a data point at the given coordinates and with the given error to the current data set in the current graph. The error-parameters are interpreted in the way specified by setting the "errors" parameter in the NewDataSet call. If you don't use error bars you can call the "DrawDataPoint" routine instead of AddDataPoint */ void GrMoveTo (double x, double y); /* set current point to x,y */ void GrLineTo (double x, double y); /* add a line from current point to x,y */ void GrMove (double x, double y); /* add x, y to the current point. */ void GrLine (double x, double y); /* add a line starting from current point, x,y long */ void GetGraphCoordinates (double* const xmin, double* const xmax, double* const ymin, double* const ymax); /* returns the axes limits of the current graph */ void CreateNewGraph(double xmin, double xmax, double ymin, double ymax, short xScaling, short yScaling); /* creates a new, empty graph with the given ranges produces a run-time error if the ranges and scaling are inconsistent xScaling/yScaling = 0 : linear = 1 : log = 2 : 1/x = 3 : probability */ void SetLineStyle(double thick, short dash); /* Sets the default line style that will be used for drawing and plotting. thick: the thickness of the line in points, dash: the dash pattern, given by the item number in the dash popup menu */ void SetFillPattern(short pattern); /* Sets the default fill pattern. pattern: the fill pattern, given by the item number in the corresponding popup menu */ void SetArrowStyle(short arrowLocation, short style, double size); /* Sets the default arrow style. You can define different arrows for line start and line end. arrowLocation: 1: at start, 2: at end, 3: both start and end style: 0: no arrow, 1..12: the item number in the arrow popup menu. size: the size of the arrow in points, as it would appear in the custom arrow dialog box. */ void SetTextStyle(const Str255 fontName, double size, short style); /* Sets the default text style. supply a font name, its size, and style. size and style are the same parameters you can pass to the MacOS routines "TextSize" and "TextFace" */ void SetNewGraphRect(double left, double top, double right, double bottom); /* Sets the default rectangle used for creating new graphs in the drawing window. */ void SetDataPointStyle(short style, double size, double thickness); /* Sets the default data point style. style gives the item number in the data points popup menu style: 0:pixel, 1-13: row number in data pont menu, 14-17: points in the last row, second column -1..-8: the 8 custom points in the separate section size: the size of the point in points, same as the one which is given in the custom data point symbols dialog box. thickness: the line thickness used to draw empty data point symbols. */ void SetBGDataPointStyle(short style, double size); /* Can be used in conjunction with SetDataPointStyle to set the default data pont style. Substitutes the background symbol of the current data point style with the one given. style and size are interpreted in the same way as for the SetDataPointStyle routine */ void SetLineColor(long red, long green, long blue); /* Sets the default line color, used for lines and text. red, green, blue give the RGB value of the color (0<red,green,blue<65536) */ void SetFillColor(long red, long green, long blue); /* Sets the default fill color, used to fill drawing shapes or for curves in plots. red, green, blue give the RGB value of the color (0<red,green,blue<65536) */ void DrawRect(double left, double top, double right, double bottom); /* Creates a rectangle with the given coordinates in the current drawing window */ void DrawEllipse(double left, double top, double right, double bottom); /* Creates an ellipse with the given coordinates in the current drawing window */ void DrawLine(double start_h, double start_v, double end_h, double end_v); /* Creates a line with the given coordinates in the current drawing window */ void DrawTextLine(const Str255 theString, double theAngle, Boolean docenter); /* Creates a text-label at the given coordinates in the current drawing window, with the given rotation angle. rotation is around center if docenter is true. */ void DrawNumber(double theNum, short decs, double theAngle, Boolean docenter); /* Converts the number into a text with the given number of decimals, and creates a text-label at the given coordinates in the current drawing window, with the given rotation angle. rotation is around center if docenter is true. */ void DrawDataPoint(double x, double y); /* Draws a data point symbol at the coordinates given, using the current data point style. if OpenDataSet was called, then it creates a data point in the current plot, adding it to the current data set. */ void DrawPICT(double left, double top, double right, double bottom, PicHandle thePict); /* Creates a new picture in the current drawing window using the MacOS PicHandle "thePict". Once you call this routine, the handle thePict BECOMES PROPERTY of pro Fit — DO NOT DISPOSE IT! left and top give the coordinates of the picture. right and bottom are used to define the size of the picture if they are larger than left and top, respectively. Otherwise the size information containd in the PicHandle passed you pass is used. */ void GetLastClickedCoordinates(double* x, double* y); /* returns the screen-coordinates that were last clicked by the user */ void DisableDrawingUpdates(void); /* Inhibits updates in the current drawing window until your program is finished. Call this if you are drawing lots of stuff and you want to do it as fast as possible. */ void OpenPolygon(short smoothing, short kind); /* Opens a new polygon definition, which can then be defined by moveto/lineto calls. smoothing: gives the kind of smoothing which is applied to the polygon, use 0 for no smoothing. kind: 0 for a normal polygon, 1 for a closed polygon. */ void ClosePolygon(void); /* Stops collecting data for a polygon definition, and creates the resulting polyon in the current drawing window. */ void GroupBegin(void); void GroupEnd(void); /* Starts/ends the definition of a group. All drawing taking place after this call will be part of a group. Call GroupEnd when you are finished with the drawing that belongs to this group. */ void SetCurrentGraph(long graphID); /* Sets the current graph, that is the graph that will be used for all newly created function-curves and data-sets, and by all routines that access the current graph in general, such as the axes-editing routines. graphID is the graph's identificatioin number, which can be found immediately after a graph is created by using the routine GetCurrentGraph. */ long GetCurrentGraph(void); /* returns the graph identification number of the current graph. */ long GetNextGraph(long graphID); /* returns the identification number of the graph following the given one in pro Fit's private list of existing graphs. The order in this list is not defined and depends on the order of the windows containing the graphs. use graphID=0 to get the ID of the first graph. returns 0 if graphID identifies the last graph, or if graphID!=0 and no graph with this identification number exists. */ void GetGraphFrame(double* left,double* top,double* right,double* bottom); /* returns the coordinates of the frame of the current graph. */ void SetGraphFrame(double left,double top,double right,double bottom); /* changes the frame of the current grapha to match the given coordinates. */ short GetCurrentAxis(short whichAxis); /* returns the number of the current x or y axis. whichAxis is either xAxis (==0) or yAxis (==1). */ void SetCurrentAxis(short whichAxis, short axisID); /* sets the current axis that will be used for the next data set or curve, and for all axis-editing calls, such as SetRange, SetAxisPosition, etc. */ void DeleteAxis(short whichAxis, short axisID); /* deletes the given axis in the current graph. */ void MakeNewAxis(short whichAxis, double min, double max, short scaling, double position); /* creates a new axis with the given range and scaling in the current graph. position gives the position of the new axis in the coordinate system of the MAIN AXIS perpendicular to it. */ void SetRange(short whichAxis, double min, double max, short scaling); /* Changes the range and scaling of the current axis to the specified one. (the current axis can be set with the SetCurrentAxis routine) */ void MakeTicks(short whichAxis, double firstMaj, double distance, short nrMinTicks); /* Lets the current axis recalculate its ticks, based on the new position of the first major tick, tick distance, and number of minor ticks. */ void SetLabelsFormat(short whichAxis, short format, short decimals); /* Changes the format of the tick labels of the current axis. format: -1: auto, 0: decimal, 1: auto exponent. any other number gives the fixed exponent decimals: number of digits after the decimal point. */ void ClearLabels(short whichAxis); /* Clears the text contained in all labels of the current axis. */ void ClearTicks(short whichAxis); /* Clears the ticks list of the current axis, effectively creating an empty list of ticks. Call this routine before defining a set of custom ticks with the AddTick routine. */ short AddTick(short whichAxis, double tickPos, Boolean isMajor); /* Use this routine to define your own ticks in the current axis. Call ClearTicks before using this routine. given the position of the tic mark and its properties (set isMajor to true to obtain a major tick), AddTick returns the index of the newly created tick in the tick list. It returns 1 for the first tick. This index can be used in the SetLabel/SetLabelText routines to change the label attached to the newly created tick. */ void SetLabel(short whichAxis, short tickNum, double labelNumber); /* Given a tick index (1<=tickNum<=numberOfTicks), this routine attaches the given label to it by converting labelNumber into a string according to the label-format specified for the current axis. labels can be attached to minor or major ticks in the same way. */ void SetLabelText(short whichAxis, short tickNum, const Str255 labelText); /* Given a tick index (1<=tickNum<=numberOfTicks), this routine attaches the given label to it by using the text passed in labelText (pascal string!) */ void SetAxisPosition(short whichAxis, double position); /* Sets the position of the current axis in the coordinate system of the MAIN AXIS perpendicular to it. */ void SetAxisAttributes(short whichAxis, long flags); /* sets the attributes of the current axis to match "flags" flags: a set of axis characteristics that can be calculated by summing the available constants. */ void SetGraphAttributes(long flags); /* sets the attributes of the current axis to match "flags" flags: a set of axis characteristics that can be calculated by summing the available constants. */ /********************************************************************************/ /***************** interaction with other functions and programs *****************/ void SetParamLimits(short paramNum, double low, double high); /* sets the limits of a parameter (of the currently running function) */ void SetParamDefaultValue(short paramNum, double value); /* sets the default values of a parameter (of the currently running function) */ void SetParamName(short paramNum, const Str255 name); /* sets the name of a parameter (of the currently running function) */ void SetParamDefaults(short paramNum,double value,short mode, const Str255 name, double low, double high); /* sets the default settings of a parameter (of the currently running function) */ /* mode is {active, inactive, constant} */ double CallFunction(const Str255 name,double xvalue); /* calls any of the functions in the func menu by its name */ short GetNumFunctionParams(const Str255 functionName); /* returns the number of parameters of a function in the func menu */ short GetFunctionParamMode(const Str255 functionName,short paramIndex); /* returns the mode of a parameter for one of the functions in the func menu */ void GetFunctionParamName(const Str255 functionName,short paramIndex, Str255 paramName); /* returns the name of a parameter for one of the functions in the func menu */ double GetFunctionParam(const Str255 functionName,short paramIndex); /* returns the value of a parameter for one of the functions in the func menu */ void SetFunctionParam(const Str255 functionName,short paramIndex,double value); /* sets a parameter value for a function in the func menu */ void CallProgram(const Str255 programName); /* calls a program from the User menu */ /********************************************************************************/ /****************************** numerical analysis ******************************/ double Integral(const Str255 functionName, double xmin, double xmax, short numIters); /* calculates the integral of a function in the func menu */ /* numIters is the number of iterations (5-15) */ double Maximum(const Str255 functionName, double xmin, double xmax); /* finds the maximum of a function in the func menu */ double Minimum(const Str255 functionName, double xmin, double xmax); /* finds the minimum of a function in the func menu */ double Root(const Str255 functionName, double xmin, double xmax); /* finds the root of a function in the func menu */ double Derivative(const Str255 functionName, double x, double scale); /* finds the derivative of a function in the func menu */ void Fit(const Str255 functionName, long xCol, long yCol, long errCol, double errVal, Boolean selectionOnly); /* runs a non-linear fit for the given function. Generates a run-time error if fit did not converge. xCol, yCol: the x- and y-columns errCol: the error column. Set to 0 if using no error or a constant / percentual error errVal: if > 0: a constant error if < 0 (-100..-0) a percentual error selectionOnly: set to true if only selected rows should be fitted */ double ChiSquared(void); /* returns the chi-squared of the last successful fit. Produces a run-time error if no fit information from a successful fit is available */ short NumFitParams(void); /* returns the number of parameters of the last successful fit (ALL parameters, active, inactive, and constant returns 0 if no fit information from a successful fit is available */ double FittedParams(short paramNum); /* returns the fitted value of a parameter. Produces a run-time error if no fit information from a successful fit is available */ double ParamSD(short paramNum); /* returns the standard deviation of a parameter after a successful fit. returns NAN (Not A Number, an invalid real number) if no standard deviation is available. Produces a run-time error if no fit information from a successful fit is available */ double CovarMatrix(short paramNum1, short paramNum2); /* returns the elements of the covariance matrix after a successful fit. returns NAN if the corresponding element is not defined because the parameter was not used for the fit. Produces a run-time error if no fit information from a successful fit is available */ double PRandom (void); /* returns a random double between 0 and 1 */ short NumberInvalid(double aNum); /* returns 1 if the argument is not a good number returns 0 if the argument is a normal, reasonable number */ double Erf(double x); /* returns the error function defined as x 2 / ------ | exp(-t*t) dt √π / 0 The definition is such that Erf(-inf) = -1, Erf(inf) = 1 */ double Erfc(double x); /* returns the complementary error function defined as 1-erf(x) */ void SetFitDefaults( short algorithm, /* algorithm to be used for fitting */ short yErrDistribution, /* y error distribution: gaussDistr, doubleExpDistr, lorentzDistr, andrewDistr, tukeyDistr */ short xErrDistribution, /* x error distribution: gaussDistr, doubleExpDistr, lorentzDistr, andrewDistr, tukeyDistr */ long xErrColumn, /* x error column: >0:column number, 0:none, -1:constant, -2:percent */ double xErrValue, /* x error value if constant (xErrColumn=-1) or percentage (xErrColumn=-2) */ double stopTime); /* criterium to stop monte carlo fits, does not stop if 0 */ /* interpreted as seconds if negativ and as iterations if positive */ /* Sets the error column and type, the algorithm and the stopping creteria to be used in all subsequent calls to Fit(..) */ Boolean Maximize( const Str255 theFunction, /* the function name in the func menu */ double precision, /* relative tolerance of function values calculated in the simplex */ /* algorithm, used as convergence criterium */ Boolean varyX, /* true, if the x-values should be varied, too */ double* x, /* on input: fixed x-value, or starting x-value if varyX is true */ /* returned x-value of maximum found */ double* y); /* returned y-value of maximum found */ /* Varies the parameters of the function (and x if varyX is true) until the function value reaches a maximum. It is a procedure comparable to fitting. The algorithm used is the Simplex method. */ Boolean Minimize(const Str255 theFunction,double precision,Boolean varyX, double* x,double* y); /* See the comment for "Maximize", which works in the same way. */ void SetErrorAnalysis( double confidence, /* confidence interval in % (set to 0 to disable error analyis) */ long iterations); /* number of iterations (set to 0 to disable error analyis) */ /* Sets the options for error analysis to be used in the next call to Fit(..) */ void ConfidenceInterval( short i,double* const min, double* const max); /* returns in min,max the confidence interval for parameter i, as calculated after the last fit by the error analysis algorithm. Note that this routine does not return meaningful results if the confidence interval for a given value was not determined, e.g. because this parameter was not active during a fit. */ Boolean CalcStat( long column, /* column number */ Boolean selRowsOnly, /* set to true to use only the selected rows */ Boolean withBasics, /* calculate basic information */ Boolean withSkewAndCurt, /* calculate skewness and curtosis */ Boolean withMedian); /* calculate median */ /* returns false if an error occurred, true if ok set "column" to: 0 to include all columns. -1 to use the current selection set the Boolean parameters corresponding to the information you want to calculate. You will use GetBasics, GetSkew, GetMedian to retrieve this information */ void GetBasics( long* count, /* number of data processed */ double* sum, /* sum of all these data */ double* mean, /* their average */ double* variance, /* variance = (stdDev)^2 */ double* stdDev, /* the standard deviation */ double* meanAbsDev); /* mean absolute deviation */ /* returns some results of the last statistics evaluation CalcStat must have been called with the withBasics parameter set to true before this function can be used. */ void GetSkewAndKurt( long* count, /* number of data processed */ double* mean, /* 1.moment of distribution: average */ /* measure the average value of a distribution */ double* variance, /* 2.moment of distribution: variance */ /* the square of the standard deviation */ double* skewness, /* 3.moment of distribution: skewness */ /* characterizes the asymmetry of a distribution around its mean */ double* kurtosis); /* 4.moment of distribution: kurtosis */ /* measure the relative peakedness or flatness of a distribution */ /* returns some results of the last statistics evaluation CalcStat must have been called with the withSkewAndCurt parameter set to true before this function can be used. */ void GetMedian( long* count, /* number of data processed */ double* mean, /* average over all data */ double* median, /* the data in the midth of the ordered sequence of data */ double* minimum, /* smallest (largest negative) value found */ double* maximum); /* largest value found */ /* returns some results of the last statistics evaluation CalcStat must have been called with the withMedian parameter set to true before this function can be used. */ /********************************************************************************/ /************************* data access routines *********************************/ long XColumn (void); /* returns the current x-column of the current data window */ long YColumn (void); /* returns the current y-column of the current data window */ long XErrColumn (void); /* returns the current x-error column of the current data window */ long YErrColumn (void); /* returns the current y-error column of the current data window */ void SetDefaultCols(long xColumn, long yColumn, long xErrColumn, long yErrColumn); /* Sets the default x, y, Δx, Δy columns of the current data window. The default x and y columns are those columns that are shown in the preview window. Default columns are also identified by small x, y, Δx, Δy lettering in the column header. Set xErrColumn and yErrColumn to 0 to "undefine" it. Use a negative number if you don't want to change a given default column. */ long NrRows (void); /* returns the number of rows in the current data window */ long NrCols (void); /* returns the number of columns in the current data window */ double GetData(long row,long column); /* returns a value from the current data window */ void SetData(long row,long column,double value); /* sets a value in the current data window */ short TestData(long row,long column); /* returns 0 if a value in the current data window is empty */ /* returns 1 otherwise */ void ClearData(long row,long column); /* clears a value from the current data window */ Rect GetSelection(void); /* returns the selected rows/columns of the current data window */ void SetColName(long column, const Str255 name); /* sets the name of a column in the current data window */ void GetColName(Str255 name, long column); /* returns the name of a column in the current data window */ void SetDataSize(long numberOfRows, long numberOfColumns); /* Resizes the current data window to match the new number of rows and columns passed as a paramter. Set a parameter to 0 if you don't want to change it. Causes a run-time error if resizing fails. */ long GetColType(long columnNumber); /* returns the type of a column of the current data window (colNumber = 1..MaxNrCols) return values: floatColumn: 4 byte floating point format doubleColumn 8 byte floating point format textColumn: text format */ void SetColType(long columnNumber, long theType); /* sets the type of a column of the current data window (colNumber = 1..MaxNrCols) theType: floatColumn: 4 byte floating point format doubleColumn 8 byte floating point format textColumn: text format Causes a run-time error if conversion failed. */ Boolean ColEmpty(long columnNumber); /* returns true if the given column doesn't contain any data, false otherwise */ void SetColWidth(long columnNumber, short width); /* sets the width of the given column to the number of pixels specified in "width" */ void SelectCells(long left, long top, long right, long bottom); /* selects the cells within the given rectangle the coordinates are clipped to the size of the data list */ void SelectRows(long top, long bottom, Boolean doSelect); /* selects or deselects the given rows doSelect==true: selects the given rows doSelect==false: deselects the given rows top and bottom are clipped to the size of the list selections outside top/bottom remain as they are */ Boolean RowSelected(long rowNumber); /* returns true if at least a cell in the given row is selected, false otherwise, or if the given row is outside the list. */ Boolean CellSelected(long row, long column); /* returns true if the given cell is selected run-time error if row/column is outside the list */ void SetCell(long row,long column, const Str255 s); /* sets the given cell to the string s. If the given cell is a numeric cell, the string is converted into a number which is used to set the value of the cell. */ void GetCell(Str255 s, long row,long column); /* returns the contents of the given cell in the string s. If the cell is a numeric cell, the number is converted into a string and returned in s. */ void GetDefaultData(DoubleArrayHandle* const xColH, DoubleArrayHandle* const yColH, DoubleArrayHandle* const xErrColH, DoubleArrayHandle* const yErrColH, LongArrayHandle* const indecesH, long* arraySize, Boolean selectedRowsOnly, DataInfo* const info); /* This routine provides you with a copy of the default x-y data in the current Data window. It allocates memory for the x,y arrays, for the x,y-Error arrays, and for the array that gives the corresponding row numbers in the data window. Then it fills them up with the data. It copies only the data where both the x and the y cell contain valid numbers. Pass nil for one of these array if you are not interested in it. IndecesH contains, for each x-y data in the data-arrays, the row number in the current data list where that data is found. when selectedRowsOnly is true, only data in selected rows is used to fill up the arrays. The arrays returned by GetDefaultData contain valid data starting from the element with index 1. The value of the element with index 0 is undefined. The last element has index "arraySize". arraySize is set to zero in case of out-of-memory situations or other problems. Provide a pointer to a data struct of type DataInfo as the last paraemter if you are interested in extra information on the data set. The elements of the DataInfo struct are set by GetDefaultData, and they tell you the boundaries of the x- and y- data, if the data is ordered with x-values growing with the index in the arrays, if any cells in the columns dedicated to the errors of the data points where found empty. See the declaration of the DataInfo structure, above. */ /********************************************************************************/ /******************************* miscellaneous *********************************/ void SetWaitTitle(const Str255 s1); /* writes the string s1 in the window put up by profit while running programs This string serves as a title. */ void SetWaitText(const Str255 s1, const Str255 s2, const Str255 s3, const Str255 s4, const Str255 s5, const Str255 s6); /* writes the strings s1-s6 in the window put up by profit while running programs in a two columns by three row arrangement: s1 s2 s3 s4 s5 s6 Use an empty string if you don't want to change it. */ double MarkedX(short i); double MarkedY(short i); /* return the x and y coordinate of a marker in the preview window. i is the index of the marker. i = 0 for the reference marker. */ void MarkedCoord(short i, double* x, double* y); /* returns the x and y coordinates of a marker in the preview window. i is the index of the marker. i = 0 for the reference marker. */ void DoMenu(const Str255 s); /* executes a menu command, with the same effect as if the command is chosen by hand. s is of the type 'MenuTitle:MenuItem' or 'MenuTitle:SubmenuTitle:MenuItem' Causes a run-time error if such a menu item does not exist. add "$OK" at the end of the string if you want to bypass dialog boxes and simulate a click on ok. */ short TestStop(void); /* returns 1 if the user interrupted execution (cmd-.), 0 otherwise */ void StopExecution(void); /* tells pro Fit to stop the execution and not call the external module /* anymore after having the current function call (First, Run, etc.) is completed.*/ short GetAndSetStatus(short newStatus, Str255 s); /* Returns the present execution status, then sets it to newStatus */ /* The status can be: */ /* 0: if normal operation */ /* 1: if the user interrupted operation */ /* 2: if a warning has been posted */ /* 3: if a run-time error has been posted */ /* Set newStatus to -1 if you don't want to change the current status */ /* If you set a status 2 or 3, pass a suitable error or warning message */ /* in s It will be shown once your module is finshed. */ /* On return, s holds the current message (if status was 2 or 3) */ /* Note, that calling StopExecution is equivalent to setting error status */ /* to 1 and TestStop returns true if error status is 1 or 3 */ /********************************************************************************/ /****************************** advanced routines *******************************/ /* The following routines are provided for the experienced programmer. They allow for more power and flexibility when writing powerful external modules. */ void HandleEvent(EventRecord* const theEvent); /* Passes theEvent to pro Fit for handling it. Use this call to handle update events when creating your own window. */ Boolean CancelEvent(EventRecord* const theEvent); /* returns true if theEvent is a key-down event for the escape key or cmd-'.' . */ void DeactivateProFitWindows(void); /* Deactivates all of pro Fit's windows and disables all menus. Call this routine before showing a window or creating a dialog. Each call to DectivateProFitWindows must be matched with a call to ActivateProFitWindows(void) */ void ActivateProFitWindows(void); /* Activates pro Fit's frontmost window and enables the menus. Call this routine after closing a window or a dialog. Each call to ActivateProFitWindows must be preceded by a call to DectivateProFitWindows(void) */ FSSpecPtr GetModuleFile(void); /* Returns a pointer to the FSSpec record of this file of this module. */ /* advanced data access routines */ void GetColHandle(long col, Handle* const colH, long* const length, long* const colType, Boolean forWriting); /* Returns a handle (colH) to the data of the given column. You can read and/or modify the data in the handle. This is much faster than accessing a column's data through GetData/SetData and GetCell/SetCell. colH: The handle to the column's data. Can be nil if the corresponding column is empty. length: the number of rows held by this column, presently always equal to the number of rows of the data window forWriting: set to true if you intend to change the contents of the column, set to false otherwise. colType: the type of the column (textColumn, floatColumn, doubleColumn) If you change the data in the returned handle, you must subsequently call SetColHandle. Do never call DisposeHandle(colH) — colH is allocated and deallocated by pro Fit. if colType = floatColumn, colH is a handle of type FloatColumnHandle (handle to an array of 4-byte floating point values) if colType = doubleColumn, colH is of type DoubleColumnHandle (handle to an array of 8-byte floating point values) if colType = textColumn, colH is of type TextColumnHandle. (handle to a record of type StringData) Note: For columns of type floatColumn and doubleColumn, the first entry of the array is reserved. The value of the first cell is found in the array element having index 1. Warning: This routine should by used by experienced programmers only. Warning: Accessing text columns in this way is _not_ recommended. The definition of the data structure may change in the future. While you are working on the data in colH, you should not call any other routines accessing the data window except GetColumnHandle and SetColumnHandle. When you modify the data in colH, you should avoid calling any pro Fit routines until you have called SetColHandle — if you want to call other pro Fit routines, first make a copy of the data by using HandToHand; once you have made all modifications to the data, call SetColHandle. */ void SetColHandle(long col, Handle colH); /* Sets a given column to the data in colH. The organization of the data in colH depends on the data type of the column: if floatColumn, colH is a handle of type FloatColumnHandle (handle to an array of 4-byte floating point values) if doubleColumn, colH is of type DoubleColumnHandle (handle to an array of 8-byte floating point values) if textColumn, colH is of type TextColumnHandle. (handle to a record of type StringData) (To get a column's type, call GetColType) Once you call SetColHandle, the handle becomes property of pro Fit — do not dispose it. colH can either be: - a handle that you allocated yourself. In this case, the Handle's size must be: 4*(nrRows+1) for columns of type floatColumn 8*(nrRows+1) for columns of type doubleColumn 14 + size of all strings for columns of type textColumn - a handle that you obtained from GetColHandle - nil if you want to clear the given column Warning: This routine should by used by experienced programmers only. Warning: Accessing text columns in this way is _not_ recommended. The definition of the data structure may change in the future. */ #endif